home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
IRIX Base Documentation 1998 November
/
IRIX 6.5.2 Base Documentation November 1998.img
/
usr
/
share
/
catman
/
u_man
/
cat3
/
Tk
/
getbitmap.z
/
getbitmap
Wrap
Text File
|
1998-10-30
|
15KB
|
265 lines
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk)))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk))))
NNNNAAAAMMMMEEEE
Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap,
Tk_FreeBitmap, Tk_GetBitmapFromData - maintain database of single-plane
pixmaps
SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
Pixmap
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((_i_n_t_e_r_p, _t_k_w_i_n, _i_d))))
int
TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp((((_i_n_t_e_r_p, _n_a_m_e_I_d, _s_o_u_r_c_e, _w_i_d_t_h, _h_e_i_g_h_t))))
Tk_Uid
TTTTkkkk____NNNNaaaammmmeeeeOOOOffffBBBBiiiittttmmmmaaaapppp((((_d_i_s_p_l_a_y, _b_i_t_m_a_p))))
TTTTkkkk____SSSSiiiizzzzeeeeOOOOffffBBBBiiiittttmmmmaaaapppp((((_d_i_s_p_l_a_y, _b_i_t_m_a_p, _w_i_d_t_h_P_t_r, _h_e_i_g_h_t_P_t_r))))
TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp((((_d_i_s_p_l_a_y, _b_i_t_m_a_p))))
AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
Tcl_Interp *_i_n_t_e_r_p (in) Interpreter to use for error
reporting.
Tk_Window _t_k_w_i_n (in) Token for window in which the
bitmap will be used.
Tk_Uid _i_d (in) Description of bitmap; see below
for possible values.
Tk_Uid *_n_a_m_e_I_d (in) Name for new bitmap to be defined.
char *_s_o_u_r_c_e (in) Data for bitmap, in standard bitmap
format. Must be stored in static
memory whose value will never
change.
int _w_i_d_t_h (in) Width of bitmap. |
int _h_e_i_g_h_t (in) Height of bitmap. |
int *_w_i_d_t_h_P_t_r (out) Pointer to word to fill in with |
_b_i_t_m_a_p's width.
int *_h_e_i_g_h_t_P_t_r (out) Pointer to word to fill in with |
_b_i_t_m_a_p's height.
Display *_d_i_s_p_l_a_y (in) Display for which _b_i_t_m_a_p was
allocated.
PPPPaaaaggggeeee 1111
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk)))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk))))
Pixmap _b_i_t_m_a_p (in) Identifier for a bitmap allocated
by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
These procedures manage a collection of bitmaps (one-plane pixmaps) being
used by an application. The procedures allow bitmaps to be re-used
efficiently, thereby avoiding server overhead, and also allow bitmaps to
be named with character strings.
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp takes as argument a Tk_Uid describing a bitmap. It returns
a Pixmap identifier for a bitmap corresponding to the description. It
re-uses an existing bitmap, if possible, and creates a new one otherwise.
At present, _i_d must have one of the following forms:
@@@@_f_i_l_e_N_a_m_e _F_i_l_e_N_a_m_e must be the name of a file containing a
bitmap description in the standard X11 or X10 format.
_n_a_m_e _N_a_m_e must be the name of a bitmap defined previously
with a call to TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp. The following names
are pre-defined by Tk:
eeeerrrrrrrroooorrrr The international "don't" symbol: a
circle with a diagonal line across it.
ggggrrrraaaayyyy55550000 50% gray: a checkerboard pattern where
every other bit is on.
ggggrrrraaaayyyy22225555 25% gray: a pattern where 25% of the bits
are on, consisting of all the bit
positions that can be reached by a chess
knight starting at (0,0).
hhhhoooouuuurrrrggggllllaaaassssssss An hourglass symbol.
iiiinnnnffffoooo A large letter ``i''.
qqqquuuueeeesssstttthhhheeeeaaaadddd The silhouette of a human head, with a
question mark in it.
qqqquuuueeeessssttttiiiioooonnnn A large question-mark.
wwwwaaaarrrrnnnniiiinnnngggg A large exclamation point.
Under normal conditions, TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp returns an identifier for the
requested bitmap. If an error occurs in creating the bitmap, such as
when _i_d refers to a non-existent file, then NNNNoooonnnneeee is returned and an error
message is left in _i_n_t_e_r_p->_r_e_s_u_l_t.
TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp associates a name with in-memory bitmap data so that the
name can be used in later calls to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. The _n_a_m_e_I_d argument
gives a name for the bitmap; it must not previously have been used in a
PPPPaaaaggggeeee 2222
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk)))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk))))
call to TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp. The arguments _s_o_u_r_c_e, _w_i_d_t_h, and _h_e_i_g_h_t
describe the bitmap. TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp normally returns TCL_OK; if an
error occurs (e.g. a bitmap named _n_a_m_e_I_d has already been defined) then
TCL_ERROR is returned and an error message is left in _i_n_t_e_r_p->_r_e_s_u_l_t.
Note: TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp expects the memory pointed to by _s_o_u_r_c_e to be
static: TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp doesn't make a private copy of this memory, but
uses the bytes pointed to by _s_o_u_r_c_e later in calls to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
Typically TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp is used by ####iiiinnnncccclllluuuuddddeeee-ing a bitmap file directly
into a C program and then referencing the variables defined by the file.
For example, suppose there exists a file ssssttttiiiipppp....bbbbiiiittttmmmmaaaapppp, which was created
by the bbbbiiiittttmmmmaaaapppp program and contains a stipple pattern. The following code
uses TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp to define a new bitmap named ffffoooooooo:
Pixmap bitmap;
#include "stip.bitmap"
Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits,
stip_width, stip_height);
...
bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));
This code causes the bitmap file to be read at compile-time and
incorporates the bitmap information into the program's executable image.
The same bitmap file could be read at run-time using TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp:
Pixmap bitmap;
bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap"));
The second form is a bit more flexible (the file could be modified after
the program has been compiled, or a different string could be provided to
read a different file), but it is a little slower and requires the bitmap
file to exist separately from the program.
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp maintains a database of all the bitmaps that are currently
in use. Whenever possible, it will return an existing bitmap rather than
creating a new one. This approach can substantially reduce server
overhead, so TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp should generally be used in preference to Xlib
procedures like XXXXRRRReeeeaaaaddddBBBBiiiittttmmmmaaaappppFFFFiiiilllleeee.
The bitmaps returned by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp are shared, so callers should never
modify them. If a bitmap must be modified dynamically, then it should be
created by calling Xlib procedures such as XXXXRRRReeeeaaaaddddBBBBiiiittttmmmmaaaappppFFFFiiiilllleeee or
XXXXCCCCrrrreeeeaaaatttteeeePPPPiiiixxxxmmmmaaaapppp directly.
The procedure TTTTkkkk____NNNNaaaammmmeeeeOOOOffffBBBBiiiittttmmmmaaaapppp is roughly the inverse of TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
Given an X Pixmap argument, it returns the _i_d that was passed to
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp when the bitmap was created. _B_i_t_m_a_p must have been the
return value from a previous call to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
TTTTkkkk____SSSSiiiizzzzeeeeOOOOffffBBBBiiiittttmmmmaaaapppp returns the dimensions of its _b_i_t_m_a_p argument in the
words pointed to by the _w_i_d_t_h_P_t_r and _h_e_i_g_h_t_P_t_r arguments. As with
TTTTkkkk____NNNNaaaammmmeeeeOOOOffffBBBBiiiittttmmmmaaaapppp, _b_i_t_m_a_p must have been created by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
When a bitmap returned by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp is no longer needed, TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp
should be called to release it. There should be exactly one call to
TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp for each call to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. When a bitmap is no longer
PPPPaaaaggggeeee 3333
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk)))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk))))
in use anywhere (i.e. it has been freed as many times as it has been
gotten) TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp will release it to the X server and delete it from
the database.
BBBBUUUUGGGGSSSS
In determining whether an existing bitmap can be used to satisfy a new
request, TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp considers only the immediate value of its _i_d
argument. For example, when a file name is passed to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp,
TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp will assume it is safe to re-use an existing bitmap created
from the same file name: it will not check to see whether the file
itself has changed, or whether the current directory has changed, thereby
causing the name to refer to a different file.
KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
bitmap, pixmap
PPPPaaaaggggeeee 4444